🔐 ConstructQ — RBAC Settings (Web) · Dev Spec · v1.0

วัตถุประสงค์

หน้านี้คือศูนย์กลางสำหรับ กำหนดบทบาทผู้ใช้งานและสิทธิ์การเข้าถึงโมดูล ในระบบ ConstructQ · รองรับ 7 system roles + custom roles · ใช้ Permission Matrix 26 modules × 5 actions (R/C/E/D/A) เป็น single source of truth

Tech Stack (Frontend)

• Framework:Next.js 14 App Router · Server Components first · ครอบ AppShell
• Language:TypeScript 5.4 (strict mode)
• Styling:Tailwind 3.4 + CSS variables (Flip7 tokens) · cn() helper
• Tables:AntD Table v5 (limited use) — สำหรับ Permission Matrix
• Forms:React Hook Form 7 + Zod 3.23 (Add/Edit Role modal)
• State:Zustand 4.5 (UI selected role) · SWR สำหรับ roles + modules data
• Modals:HeadlessUI Dialog หรือ AntD Modal
• i18n:next-intl 3.x · TH/EN cascade

Tech Stack (Backend)

• Framework:Go 1.22 + go-chi/v5 (~14 endpoints สำหรับ RBAC)
• DB:PostgreSQL 15 · tables: roles · modules · permissions
• Auth:JWT bearer · ตรวจสิทธิ์ผ่าน RequirePerm("m_rbac", action)
• Audit:AuditMiddleware บันทึก before/after ทุก write
• Validation:go-playground/validator · custom role code format

File Structure

// src/app/[locale]/(app)/setting/master/rbac/
├── page.tsx                 // Server Component · fetch initial
├── actions.ts               // Server Actions (RBAC mutations)
├── schema.ts                // Zod schemas (Role · Permission)
├── store.ts                 // Zustand UI state
└── components/
    ├── RBACPageClient.tsx     // Top-level client wrapper
    ├── RolesList.tsx         // 7 roles + custom + Add button
    ├── PermissionMatrix.tsx  // 26 modules × 5 actions
    ├── RoleModal.tsx         // Create/Edit role dialog
    ├── CodeSwitcher.tsx      // Auto/Manual code toggle
    └── DeleteRoleConfirm.tsx // Soft-delete confirm

Route & AppShell Wrapping

// src/app/[locale]/(app)/layout.tsx — already wraps AppShell
export default async function AppLayout({ children }: { children: React.ReactNode }) {
  return (
    <AppShell>
      <Sidebar />
      <Topbar />
      <Breadcrumb />
      <main className="content-wrap">{children}</main>
    </AppShell>
  );
}

Page Component (Server)

// page.tsx
import { requirePerm } from '@/lib/rbac/guard';
import { RBACPageClient } from './components/RBACPageClient';

export default async function RBACPage() {
  await requirePerm('m_rbac', 'view');             // 🛡️ guard

  const [roles, modules, permissions] = await Promise.all([
    fetch(`${API}/api/roles`).then(r => r.json()),
    fetch(`${API}/api/modules`).then(r => r.json()),
    fetch(`${API}/api/permissions`).then(r => r.json())
  ]);

  return <RBACPageClient
    initialRoles={roles}
    modules={modules}
    initialPermissions={permissions}
  />;
}

Server vs Client

7 Roles

26 Modules · grouped

• ภาพรวม:m_dash
• งานหลัก · โครงการ/ไซต์:m_proj · m_doc · m_wbs
• งานหลัก · ตรวจสอบคุณภาพ:m_task · m_check · m_wf
• งานหลัก · NCR:m_ncr · m_rpt
• ตั้งค่า · ฉัน:m_profile · m_co · m_bill · m_notif · m_lang
• ตั้งค่า · Master Data:m_menu · m_pkg · m_rbac · m_usr · m_addr · m_dept · m_btype · m_ptype · m_dtype · m_terms · m_pdpa · m_audit

5 Actions + Permission Encoding

PERM_MATRIX (Typescript)

// src/lib/rbac/matrix.ts
export type PermCode = 'F' | '4' | '3' | 'V' | 'N';
export const ROLE_INDEX: Record<RoleCode, number> = {
  platform_admin: 0, org_admin: 1, pm: 2, qc_mgr: 3, qc_insp: 4, sub: 5, ceo: 6
};

// Order: [platform_admin, org_admin, pm, qc_mgr, qc_insp, sub, ceo]
export const PERM_MATRIX: Record<ModuleId, PermCode[]> = {
  m_dash:    ['F','F','F','F','4','4','4'],
  m_proj:    ['F','F','F','N','N','N','N'],
  m_check:   ['F','F','V','F','N','N','N'],
  m_rpt:     ['4','4','4','4','3','3','3'],
  m_terms:   ['4','N','N','N','N','N','N'],
  m_audit:   ['4','N','N','N','N','N','N'],
  // ... full 26 modules
};

export const EXPANDED_PERMS: Record<PermCode, Record<ActionCode, boolean>> = {
  F: { view:true, create:true, edit:true, delete:true, approve:true },
  '4': { view:true, create:true, edit:true, delete:true, approve:false },
  '3': { view:true, create:true, edit:true, delete:false, approve:false },
  V: { view:true, create:false, edit:false, delete:false, approve:false },
  N: { view:false, create:false, edit:false, delete:false, approve:false }
};

UI Mockup · Full Page

Layout Grid

<div className="grid grid-cols-12 gap-6">
  <aside className="col-span-3">
    <RolesList />
  </aside>
  <main className="col-span-9">
    <PermissionMatrix roleId={selectedRoleId} />
  </main>
</div>

Component Breakdown

API Calls

Critical Actions

// Zustand store
export const useRBACStore = create<State>((set) => ({
  selectedRoleId: 'platform_admin',                     // default
  setSelectedRoleId: (id: string) => set({ selectedRoleId: id })
}));

// RoleCard click handler
const selectRole = (id: string) => {
  setSelectedRoleId(id);
  analytics.track('rbac.role_selected', { role_id: id });
};

Edit / Delete (System role protection)

const handleEdit = (role: Role) => {
  if (role.is_system) {
    toast.warning(t('rbac.systemRole.cannotEdit'));
    // ⚠️ ยังเปิด modal ได้ — แต่ name + code disabled
  }
  openRoleModal({ mode: 'edit', role });
};

const handleDelete = (role: Role) => {
  if (role.is_system) {
    toast.error(t('rbac.systemRole.cannotDelete'));
    return;
  }
  openDeleteConfirm(role);
};

UI Mockup · Matrix Row

PermissionMatrix Component (TSX)

'use client';
import { useState, useTransition } from 'react';
import { updatePermissionAction } from '../actions';

interface Props {
  roleId: string;
  modules: Module[];
  permissions: Permission[];
  editMode: boolean;
}

export function PermissionMatrix({ roleId, modules, permissions, editMode }: Props) {
  const [optimistic, setOptimistic] = useState(permissions);
  const [pending, startTransition] = useTransition();

  const grouped = groupBySection(modules);

  const handleToggle = (moduleId: string, action: ActionCode, checked: boolean) => {
    // 1) Optimistic UI
    setOptimistic(prev => applyToggle(prev, roleId, moduleId, action, checked));

    // 2) Server Action
    startTransition(async () => {
      try {
        await updatePermissionAction({ roleId, moduleId, action, granted: checked });
      } catch (e) {
        setOptimistic(permissions);                          // rollback
        toast.error(t('rbac.updateFailed'));
      }
    });
  };

  return (
    <div className="divide-y divide-ink-100">
      {Object.entries(grouped).map(([section, mods]) => (
        <section key={section}>
          <div className="bg-teal-bg px-4 py-2 font-bold text-teal-dark">{section}</div>
          {mods.map(m => (
            <ModuleRow key={m.id} module={m} permissions={optimistic}
              roleId={roleId} editMode={editMode} onToggle={handleToggle} />
          ))}
        </section>
      ))}
    </div>
  );
}

API Calls

Display Mode (View vs Edit)

• View mode (default):Checkboxes disabled · ใช้สีเขียวสำหรับ ✓ · gray dot สำหรับ ✕
• Edit mode:กดปุ่ม "แก้ไขสิทธิ์" → checkbox enabled · save แต่ละการกดผ่าน PATCH · optimistic UI
• Code badge:แสดง encoded code (F/4/3/V/N) ด้านขวาของแต่ละแถวเพื่อ debug

UI Mockup

Zod Schema

// schema.ts
export const RoleSchema = z.object({
  name_th: z.string().min(2, t('rbac.nameTooShort')).max(50),
  name_en: z.string().min(2).max(50),
  code: z.string()
    .regex(/^[a-z][a-z0-9_]{1,29}$/, t('rbac.codeFormat')),
  code_auto: z.boolean().default(true),
  description: z.string().max(500).optional(),
  color: z.string().regex(/^#[0-9A-Fa-f]{6}$/).optional(),
  is_system: z.boolean().default(false)
});

export type RoleForm = z.infer<typeof RoleSchema>;

Critical Actions

Server Action (Create)

'use server';

export async function createRoleAction(formData: RoleForm) {
  await requirePerm('m_rbac', 'create');

  const parsed = RoleSchema.safeParse(formData);
  if (!parsed.success) throw new ValidationError(parsed.error);

  const idempotencyKey = crypto.randomUUID();

  try {
    const role = await api.post('/api/roles', parsed.data, {
      headers: { 'X-Idempotency-Key': idempotencyKey }
    });
    revalidatePath('/setting/master/rbac');
    return { ok: true, role };
  } catch (e) {
    if (e.code === 'DUPLICATE_CODE') {
      return { ok: false, error: t('rbac.duplicateCode') };
    }
    throw e;
  }
}

Behavior

• Auto mode (default):Code generated อัตโนมัติจาก name_en · readonly input · slugify + lowercase + replace spaces with underscore
• Manual mode:User พิมพ์ code เอง · validate regex ^[a-z][a-z0-9_]{1,29}$
• System roles:Code disabled ทั้ง mode · ห้ามแก้

Implementation (RHF + watch)

const { watch, setValue, register, formState } = useForm<RoleForm>({
  resolver: zodResolver(RoleSchema),
  defaultValues: { code_auto: true, is_system: false }
});

const nameEn = watch('name_en');
const codeAuto = watch('code_auto');
const isSystem = watch('is_system');

// Auto-generate code when name_en changes (only in auto mode)
useEffect(() => {
  if (codeAuto && nameEn) {
    const generated = nameEn
      .toLowerCase()
      .trim()
      .replace(/[^a-z0-9\s]/g, '')
      .replace(/\s+/g, '_')
      .slice(0, 30);
    setValue('code', generated, { shouldValidate: true });
  }
}, [nameEn, codeAuto, setValue]);

// Code input
<input
  {...register('code')}
  readOnly={codeAuto || isSystem}
  className={cn('input', (codeAuto||isSystem) && 'bg-ink-50 text-ink-500')}
/>

Constraints

Backend Guard (Go)

func UpdateRoleHandler(w http.ResponseWriter, r *http.Request) {
  roleID := chi.URLParam(r, "id")
  role, err := repo.GetRole(roleID)
  if err != nil { http.Error(w, "404", 404); return }

  var input RoleUpdateInput
  json.NewDecoder(r.Body).Decode(&input)

  // System role guard
  if role.IsSystem {
    if input.Code != nil && *input.Code != role.Code {
      http.Error(w, "FORBIDDEN: cannot change system role code", 403)
      return
    }
  }

  // Org scope (non-platform_admin)
  if ctx.Role != "platform_admin" && role.OrganizationID != ctx.OrgID {
    http.Error(w, "FORBIDDEN: cross-org", 403)
    return
  }

  updated, err := repo.UpdateRole(roleID, input)
  // AuditMiddleware logs before/after automatically
}

Full API Catalog

PATCH Permissions Payload

// PATCH /api/roles/{id}/permissions
{
  "permissions": [
    { "module_id": "m_ncr", "actions": ["view", "create", "edit", "approve"] },
    { "module_id": "m_rpt", "actions": ["view", "create", "edit", "delete"] }
  ]
}

// Response: 200 OK + updated permissions list

Audit Events

PII Protection (PDPA)

• ห้ามเก็บ:password_hash · tokens · gov ID ใน audit_log.before/after
• Whitelist columns:code, name_th, name_en, description, color, is_system, permissions[]
• Storage:audit_logs ใน PostgreSQL · PG trigger block UPDATE/DELETE
• Retention:≥ 5 ปี ตาม PDPA + ประมวลรัษฎากร

Authorization Layers